package org.apache.catalina;
import javax.servlet.Servlet;
import javax.servlet.ServletException;
import javax.servlet.UnavailableException;

/**
Wrapper 是一个容器，代表 一个servlet定义。
它提供了一种方便的机制来使用拦截器，该拦截器可以查看此定义所代表的每个servlet请求。
Wrapper的实现负责管理其底层servlet类的生命周期，调用init()和destroy()和SingleThreadModel的声明。
Wrapper的父Container 通常是Context的实现， 代表这个 servlet context (and
therefore the web application) within which this servlet executes.
子容器不允许on Wrapper implementations。
*/

public interface Wrapper extends Container {
    /**返回 servlet可用的时间，毫秒。 
        如果此日期/时间是将来，则对此servlet的任何请求都将返回SC_SERVICE_UNAVAILABLE错误。
         如果它为零，则servlet当前可用。等于Long.MAX_VALUE的值被认为意味着不可用性是永久性的。
     */
    public long getAvailable();

    public void setAvailable(long available);

    //返回此servlet的JSP文件的上下文相关URI
    public String getJspFile();

    //设置此servlet的JSP文件的上下文相关URI
    public void setJspFile(String jspFile);

    //加载启动顺序值 (负值表示第一次调用时候加载).
    public int getLoadOnStartup();

    //设置加载启动顺序值 (negative value means
    public void setLoadOnStartup(int value);

    //返回此servlet的run-as标识
    public String getRunAs();

    public void setRunAs(String runAs);

    //返回此servlet的完全限定servlet类名
    public String getServletClass();

    public void setServletClass(String servletClass);

    //这个servlet目前是否可用
    public boolean isUnavailable();

    //为此servlet添加新的servlet初始化参数
    public void addInitParameter(String name, String value);

    //添加一个对InstanceEvents感兴趣的新监听器
    public void addInstanceListener(InstanceListener listener);

	  /**
	      将新的安全角色引用记录添加到此servlet的记录集
	  name servlet中使用的角色名称
	  link Web应用程序中使用的角色名称
	  description 此安全角色引用的描述
	  */
    public void addSecurityReference(String name, String link);

    /**
       分配此Servlet的初始化实例，该实例已准备好调用其service（）方法。 如果servlet类没有实现SingleThreadModel, 
      仅仅初始化的实例立即返回.  如果实现SingleThreadModel,Wrapper实现必须确保这个实例不在再次分配，直到被调用deallocate()方法来分配。
     */
    public Servlet allocate() throws ServletException;

    /**
	 将此先前分配的servlet返回到可用实例池。 如果此servlet类未实现SingleThreadModel，
	  不需要任何动作。
     */
    public void deallocate(Servlet servlet) throws ServletException;

    public String findInitParameter(String name);

    //names of all parameters of this servlet.
    public String[] findInitParameters();

    //security role link of name, 
    public String findSecurityReference(String name);

    // 所有security role reference names of this servlet, 
    public String[] findSecurityReferences();

    //如果还没有至少一个初始化实例，则加载并初始化此servlet的实例。  加载servlets 被标记 在服务启动时候加载。
    public void load() throws ServletException;

    //Remove parameter from this servlet.
    public void removeInitParameter(String name);

    //Remove InstanceEvents listener
    public void removeInstanceListener(InstanceListener listener);

    //Remove any security role reference of the specified role name.
    public void removeSecurityReference(String name);

    //处理UnavailableException，将此servlet标记为在指定的时间内不可用。
    public void unavailable(UnavailableException unavailable);


    /**
     卸载此servlet的所有已初始化实例，在为每个实例调用destroy（）方法之后.  在关闭整个servlet引擎之前，或者
    重新加载所有类之前 from the Loader associated with our Loader's repository.
     */
    public void unload() throws ServletException;
}
